Skip to content

timers: runtime-deprecate Timeout.prototype[Symbol.dispose] - #64615

Open
mcollina wants to merge 2 commits into
nodejs:mainfrom
mcollina:fix/dep0208-timeout-symbol-dispose
Open

timers: runtime-deprecate Timeout.prototype[Symbol.dispose]#64615
mcollina wants to merge 2 commits into
nodejs:mainfrom
mcollina:fix/dep0208-timeout-symbol-dispose

Conversation

@mcollina

@mcollina mcollina commented Jul 20, 2026

Copy link
Copy Markdown
Member

Emit a DEP0208 runtime deprecation warning when
Timeout.prototype[Symbol.dispose] is called.

The web platform setTimeout() / setInterval() APIs return a number,
which cannot implement Symbol.dispose. Leaving this integration in place
encourages code that is incompatible between Node.js and browsers (and
other server-side platforms that follow the web timers API).

Immediate.prototype[Symbol.dispose] is intentionally left unchanged,
since setImmediate is not a web platform API.

Prefer clearTimeout() to cancel a timeout.

Fixes: #58689

@nodejs-github-bot

nodejs-github-bot commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/userland-migrations

@nodejs-github-bot nodejs-github-bot added needs-ci PRs that need a full CI run. timers Issues and PRs related to timers, setImmediate(), setInterval(), and setTimeout(). labels Jul 20, 2026
@mcollina
mcollina force-pushed the fix/dep0208-timeout-symbol-dispose branch 2 times, most recently from 669757d to c6558b0 Compare July 20, 2026 08:49
AugustinMauroy
AugustinMauroy reviewed Jul 20, 2026
View reviewed changes
Comment thread doc/api/deprecations.md
[`setTimeout()`][] and [`setInterval()`][] APIs return a number, which cannot
implement `Symbol.dispose`. Prefer [`clearTimeout()`][] instead to cancel a
timeout. This deprecation does not apply to [`Immediate`][] objects returned by
[`setImmediate()`][].

@AugustinMauroy AugustinMauroy Jul 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since this deprecation have clear before after change could you add code snippets to that.

@mcollina

mcollina commented Jul 20, 2026

Copy link
Copy Markdown
Member Author

Added before/after code snippets to DEP0208 as requested.

mcollina added a commit to mcollina/node that referenced this pull request Jul 20, 2026
@mcollina
doc: add before/after snippets for DEP0208
13422f2 
Add code examples showing migration from
Timeout.prototype[Symbol.dispose] to clearTimeout().

Refs: nodejs#64615
Signed-off-by: Matteo Collina <hello@matteocollina.com>
@Renegade334

Renegade334 commented Jul 20, 2026

Copy link
Copy Markdown
Member

Immediate.prototype[Symbol.dispose] is intentionally left unchanged,
since setImmediate is not a web platform API.

Web or not, I'd add a +1 for deprecating this as well for consistency, are there any real uses for disposing of an Immediate in the same block as it was created?

https://github.com/search?q=language%3AJavaScript+%2Fusing+%5CS%2B+%3D+setImmediate%2F&type=code

@codecov

codecov Bot commented Jul 20, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.28%. Comparing base (357ba2f) to head (5c53996).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files 
@@            Coverage Diff             @@
##             main   #64615      +/-   ##
==========================================
- Coverage   90.29%   90.28%   -0.02%     
==========================================
  Files         790      790              
  Lines      271882   271883       +1     
  Branches    51899    51906       +7     
==========================================
- Hits       245485   245456      -29     
- Misses      16888    16931      +43     
+ Partials     9509     9496      -13
Files with missing lines Coverage Δ
lib/timers.js 100.00% <100.00%> (ø)

... and 29 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

AugustinMauroy
AugustinMauroy approved these changes Jul 20, 2026
View reviewed changes

@AugustinMauroy AugustinMauroy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in term of docs it's super nice.

and in terms of the deprecation LGTM

@avivkeller avivkeller added the semver-major PRs that contain breaking changes and should be released in the next major version. label Jul 24, 2026
@mcollina mcollina added request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. tsc-agenda Issues and PRs to discuss during Technical Steering Committee meetings. labels Jul 25, 2026
@github-actions github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Jul 25, 2026
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

This comment was marked as outdated.

Sign in to view
@nodejs-github-bot

nodejs-github-bot commented Jul 25, 2026

Copy link
Copy Markdown
Collaborator

CI: https://ci.nodejs.org/job/node-test-pull-request/75142/

This was referenced Jul 26, 2026
Open
Open
aduh95
aduh95 approved these changes Aug 5, 2026
View reviewed changes

@aduh95 aduh95 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would be interested to see this API back in a web-compat way, but in the mean time deprecating makes sense

This was referenced Aug 6, 2026
Closed
Open
@RafaelGSS RafaelGSS removed the tsc-agenda Issues and PRs to discuss during Technical Steering Committee meetings. label Aug 19, 2026
@mcollina
timers: runtime-deprecate Timeout.prototype[Symbol.dispose]
9a21601 
Emit a DEP0210 deprecation warning when
Timeout.prototype[Symbol.dispose] is called. The web platform
setTimeout()/setInterval() APIs return a number, which cannot
implement Symbol.dispose. Prefer clearTimeout() instead.
Immediate.prototype[Symbol.dispose] is left unchanged.

Fixes: nodejs#58689

Signed-off-by: Matteo Collina <hello@matteocollina.com>
@mcollina
doc: add before/after snippets for DEP0210
5c53996 
Add code examples showing migration from
Timeout.prototype[Symbol.dispose] to clearTimeout().

Refs: nodejs#64615
Signed-off-by: Matteo Collina <hello@matteocollina.com>
@mcollina
mcollina force-pushed the fix/dep0208-timeout-symbol-dispose branch from 13422f2 to 5c53996 Compare September 19, 2026 16:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jasnell jasnell jasnell approved these changes
@legendecas legendecas legendecas approved these changes
@aduh95 aduh95 aduh95 approved these changes
@RafaelGSS RafaelGSS RafaelGSS approved these changes
@avivkeller avivkeller avivkeller approved these changes
@islandryu islandryu islandryu approved these changes
+1 more reviewer
@AugustinMauroy AugustinMauroy AugustinMauroy approved these changes
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

needs-ci PRs that need a full CI run. semver-major PRs that contain breaking changes and should be released in the next major version. timers Issues and PRs related to timers, setImmediate(), setInterval(), and setTimeout().

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Remove Symbol.dispose integration in setTimeout and setInterval

10 participants

@mcollina @nodejs-github-bot @Renegade334 @jasnell @legendecas @aduh95 @RafaelGSS @avivkeller @islandryu @AugustinMauroy